BMUG PD-ROM 1995 Fall/PD-ROM F95.toast/Programming/Programming Utilities/String Magic 1.0 ƒ/Docs

Text File | 1991-04-24 | 12.3 KB | 352 lines | [TEXT/ttxt]

                                                 24 Apr 91

String Magic - V1.0
String Resource Maintenance Application
© 1991 By Curt Sellmer



1. Introduction

String Magic is an application which simplifies the maintenance of
string resources by associating symbolic names with each
string in the resource.  When you add or delete strings,
String Magic automatically updates the symbolic references.
String Magic supports 'STR#' resources but also implements two
new string resource types:  'STR2' and 'STR3'.  'STR2' is an
indexed string resource.  This means that loading a
particular string from the resource can be much faster than
when using 'STR#' resources.  'STR3' is an indexed string
resource system that requires less application memory.
String Magic can generate Resource files or rez source code files.
Addionally, String Magic always generates a header file containing
#defines's for all of your symbolic names.

The header file is named by appending a .h to the source
file name.
The resource is named by appending .rsrc, and
the rez source file is named by appending .r

    __________________________________________________________________
    For Example:

    Source:     Example.str

    Header:        Example.str.h
    Resource:    Example.str.rsrc
    Rez:        Example.str.r
    __________________________________________________________________



2. User Interface

To use String Magic you must first select a source file.  After
selecting a source file, String Magic will pick default names for
the resource and header files. You may change these if you wish.
Simply press the select button next to the appropriate field
and you will be presented with a standard file box.

Next choose the resource type that you wish to generate.  There
are three radio buttons from which you may choose 'STR3', 'STR2',
or 'STR#'.

If you want to generate source files for the MPW Rez tool, then
click on the Rez check the "Generate Rez Source" checkbox.  If
this box is not checked, then String Magic will create a file
with an empty data fork, and a resource fork containing your
resources.

The Append resource check box is useful when you want to add or
replace a string resource in an existing file.

Finally click on the "Compile" button to generate the resource and
header file from the selected source file.

3. String Magic Source Format

Each source file contains descriptions for one or more string
resources.  The input format is always the same regardless
of which resource type you choose to use.  This allows a lot
of flexibility choosing the right resource type for a specific
application. (See Choosing the right resource type.)

Each new resource is introduced by a Resource header consisting
of a percent character (%) followed by the symbolic Resource name
and the Resource number.  Resource attributes may optionally
follow.

    __________________________________________________________________
    # For example to begin a resource called 'HelpStrings' that is a
    # discardable resource you would enter:

    %HelpStrings 128 discardable
    __________________________________________________________________

The resource number may be any number specified in decimal or
hexidecimal (precede hex numbers with 0x).  For 'STR3' resources
the resource number MUST be in the range 128 - 143.

White space (including end of line characters) is used only to
delimit identifiers and keywords (See Identifiers and Keywords below)
One exception is within quoted strings as discussed below.

    __________________________________________________________________
    # Therefore the follow is equivalent to the previous example:

    %
    HelpStrings 128
                discardable
    __________________________________________________________________


After the Resource header comes the string definitions.  A string
definition consists of a String Name and a String value.

    __________________________________________________________________
    # This example shows two resource definitions:

    %
    HelpStrings  128 preload
    AboutMessage    "Wizbang is the coolest new Mac App around"
    FileMenuMessage    "The File Menu allows you to Open Wizbang documents"
    EditMenuMessage    "The Edit Menu allows you to correct mistakes"

    %
    ButtonStrings 129
    sOK "OK" sCancel "Cancel" sDefaults "Defaults"

    __________________________________________________________________



Identifiers and Keywords

Identifiers are used to symbolically represent Resource Names, and
Names.  Identifiers follow the same rules as for C programs.  They
may contain Letters, digits, and underscore characters.  They may
not begin with a digit.  Identifiers should not exceed 63
characters.

The following keywords are recognized by String Magic.  They
represent resource attributes similar to those accepted
by rez.  The keywords are case sensitive.  See Inside Mac Vol I
for a descripion of resource attributes.

    appHeap            (default)
    sysHeap

    nonPurgeable    (default)
    purgeable

    unlocked        (default)
    locked

    unprotected        (default)
    protected

    nonPreload        (default)
    preload


    changed            (Ignored)
    unchanged        (Ignored)

If two conflicting attributes are specified, the one specified last
takes precedence.

Strings

String Magic is very flexible in how it accepts string values.  The only
rule is that the string MUST be enclosed within double quote (")
characters.  The string may span more than one line.  In this case
the new line character IS part of the resulting string.  This makes
it conventent when entering multi-line strings because you can
enter the string exactly the way you want it to be seen.

Additionally the following characters sequences are special
when they appear within string values:
    \t    - Generates a horizontal tab         (ascii 9)
    \b    - Generates a backspace character     (ascii 8)
    \r    - Generates a linefeed                 (ascii 10)
    \n    - Generates a carriage return         (ascii 13)
    \f    - Generates a form feed             (ascii 12)
    \v    - Generates a vertical tab             (ascii 11)
    \?    - Generates an ascii del character     (ascii 127)

    \\    - Generates a backslash
    \"    - Generates a double quote
    \'    - Generates a single quote - Not necessary but useful for
                                     compatibility with other languages

    \$??                 - Ascii hex value
    \0x??? or \0X???    - Ascii hex value
    \0d??? or \0D???    - Ascii decimal value
    \???                - Ascii octal value
    \b???????? or
    \B????????            - Ascii binary value

    \  followed by a new line continues the line similar
       to the C language.

    __________________________________________________________________
    # The three strings in the following resource are equivalent:
    (Assume that the left edge of this example is column 1)

    % TwoLineStrings 129

    # Uses \n to enter a carriage return
    string1 "This is a\ntwo line string"

    # Uses a real carriage return.
    string2 "\
    This is a
    two line string"

    # Uses a hexidecimal ascii value to enter a carriage return
    string3 "This is a\0x0Dtwo line string"
    __________________________________________________________________

Comments
A comment is delimited by a hash (#) and the end of the line.
A comment may appear any where in a source file (except within
a quoted string.)

Operators

There are only two operators recognized by String Magic.  The first is the
New Resource operator (%) which introduces a new Resource.

The second operator is the New Block operator (+) which is used to
group strings in 'STR3' resources.  The New Block operator is ignored
when generating 'STR2' and 'STR#' resources.  See the description
of 'STR3' resources for more information about the (+) operator.

4. Choosing the right resource type.

'STR#' RESOURCES
----------------
The standard indexed string resource 'STR#' has two pitfalls
if you need access to a large number of strings.  First of all
each time you load a string with GetIndString(), ALL of the
strings in the resource must be loaded into memory.  Second,
the routine must to a linear search to locate the specific string
that you want.  If your resource contains several hundred strings,
then accessing those toward the end of the list can be real slow.

'STR#' resources should only be use when you have a very small number
of strings (less than 20) to store in the resource.

'STR2' RESOURCES
----------------
'STR2' resources are similar to 'STR#' resources in that when you load
a specific string, you must load all of the strings in the resource
into memory.  However, 'STR2' resources also contain an index which
allows accessing of the string to be accomplished in much less time.
At the front of the resource is a table which contains an index to
every 16 string block in the resource.  Therefore  accessing a
single string takes at most 17 index computations.  One to get the
block index, and 16 (worst case) to get the string within the block.
Compare that to the 300 or more index computations needed for a large
'STR#' resource.

'STR3' RESOURCES
----------------
'STR3' resources address both pitfalls discussed above.  A 'STR3'
resource is actually a collection of resources.  Each 'STR3'
resource contains at most 16 strings.  Therefore when you need to
load a specific string, the resource manager never loads more than
16 strings into memory at one time.  This also means that for any
string, no more than 16 index computations are ever needed.

When you define a 'STR3' resource in a String Magic source file, String Magic
actually creates a separate resource for each block of 16 strings.

The resource ID that you specify for a 'STR3' resource is actually
a Master ID.  String Magic uses this Master ID to generate the real
resources ID's for each 'STR3' resource.

To generate the real resource ID the following scheme is used:
First we first subtract 128 from the Master ID. This gives
us a value between 0 and 15.  (Remember that resource number for
'STR3' resources must be in the range 128 - 143).
The above value is placed in the upper 4 bits of the real resource ID.
Then we put the block number int the remaining 12 bits.

    __________________________________________________________________
    # For example:
    %
    MyStrings 128
    s1 "aaa" s2 "bbb" s3 "ccc" s4 "ddd" s5 "eee" s6 "fff"
    s7 "ggg" s8 "hhh" s9 "iii" s10 "jjj" s11 "kkk" s12 "lll"
    s13 "mmm" s14 "nnn" s15 "ooo" s16 "ppp" s17 "qqq" s18 "rrr"

    # Would generate two 'STR3' Resources:
    Resource 1 would contain:
        "aaa" "bbb" "ccc" "ddd" "eee" "fff" "ggg" "hhh" "iii"
        "jjj" "kkk" "lll" "mmm" "nnn" "ooo" "ppp"

    Resource 2 would contain:
        "qqq" "rrr"
    __________________________________________________________________

The first actual resource for the 'STR3' resource specified as
resource number 129 in the input file would have the real ID
number of: 0x1001 or 4097

To get a better feel for how this works, create a small source file
and compile it with the -src option.

    String Magic -src test.str

This will generate a commented rez source file.

When creating 'STR3' resources it is sometimes convenient to group
strings that will be used together into the same block.  This way
they will all be loaded into memory by the resource manager at the
same time.  To acomplish this you can use the New Block
operator (+).  When String Magic Encounters a + in the input file,
it will start a new block (ie. resource). This way you can
be assured that the next 16 strings will all be in the same
resource.  If the (+) operator occurs in a position where a new
block would have been started anyway then it has no effect.  In other
words, it will not cause a block to be skipped.

5.  Loading Strings.

To load a string from a 'STR#' resource you use the Toolbox routine
GetIndString.  The prototype looks like this:
pascal void GetIndString(Str255 buf, short ResID, short index);

For ResID you simply use the name of the resource as specifed in
the String Magic source file. And for the index you use the String Name.

Similarly for 'STR2' and 'STR3' resources you would use:
GetIndStr2() and GetIndStr3() respectively.  These routines take
the same parameters as GetIndString.

To access the GetIndStr2() and GetIndStr3() routines you
must link you program with FastStrings.c.o.  I suggest putting
this file in your {CLibraries} directory.

6. Use of String Magic and supporting routines.

            String Magic V1.0 is FREE.

You may use String Magic and the supporting routines
free of charge.

If you have any Questions or Comments you can contact me at:

America Online: Screen Name "CurtS5"

I'd like to know whether you found String Magic useful or not.
Help keep the dust out of my AO mailbox, send me some mail!

or

Curt Sellmer
11028 Jollyville Road #342
Austin, TX  78759